---
title: Print
icon: '#pro/Printer'
---

<MetaData
  lang="en-US"
  isPro
  meta={{
    preset: [{
      client: '@univerjs/preset-sheets-advanced',
      locale: '@univerjs/preset-sheets-advanced/locales/en-US',
      style: '@univerjs/preset-sheets-advanced/lib/index.css',
    }],
    plugins: [{
      client: '@univerjs-pro/sheets-print',
      facade: '@univerjs-pro/sheets-print/facade',
      locale: '@univerjs-pro/sheets-print/locale/en-US',
      style: '@univerjs-pro/sheets-print/lib/index.css',
    }],
    server: 'No',
  }}
/>

Print functionality allows users to print spreadsheet content as physical documents or export it to PDF format for offline viewing and sharing.

<PlaygroundFrame lang="en-US" slug="sheets/print" clickToShow />

## Preset Mode

The print functionality is included in the `@univerjs/preset-sheets-advanced` preset.

### Installation

<Callout>
  The `UniverSheetsAdvancedPreset` preset from `@univerjs/preset-sheets-advanced` depends on the `UniverSheetsDrawingPreset` preset at runtime. Please install `@univerjs/preset-sheets-drawing` first.
</Callout>

```package-install
npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

### Usage

```typescript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced' // [!code ++]
import UniverPresetSheetsAdvancedEnUS from '@univerjs/preset-sheets-advanced/locales/en-US' // [!code ++]
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing' // [!code ++]
import UniverPresetSheetsDrawingEnUS from '@univerjs/preset-sheets-drawing/locales/en-US' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css' // [!code ++]
import '@univerjs/preset-sheets-advanced/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.En_US,
  locales: {
    [LocaleType.En_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsDrawingEnUS, // [!code ++]
      UniverPresetSheetsAdvancedEnUS, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(), // [!code ++]
    UniverSheetsAdvancedPreset(), // [!code ++]
  ],
})
```

If you have a commercial license for Univer, please refer to [Using License in Client](/guides/pro/license#in-preset-mode) for configuration.

### Presets and Configuration

```typescript
interface IUniverSheetsAdvancedPresetConfig {
  print?: Partial<IUniverSheetsPrintConfig>
}

interface IUniverSheetsPrintConfig {
  /**
   * Whether to force the watermark to be displayed when printing
   * @default false
   */
  enforceWatermark?: boolean
}
```

## Plugin Mode

### Installation

```package-install
npm install @univerjs-pro/sheets-print
```

### Usage

```typescript
import { UniverSheetsPrintPlugin } from '@univerjs-pro/sheets-print' // [!code ++]
import SheetsPrintPluginEnUS from '@univerjs-pro/sheets-print/locale/en-US' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

import '@univerjs-pro/sheets-print/lib/index.css' // [!code ++]

const univer = new Univer({
  locale: LocaleType.En_US,
  locales: {
    [LocaleType.En_US]: mergeLocales(
      SheetsPrintPluginEnUS, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverSheetsPrintPlugin) // [!code ++]
```

If you have a commercial license for Univer, please refer to [Using License in Client](/guides/pro/license#in-plugin-mode) for configuration.

### Plugins and Configuration

```typescript
interface IUniverSheetsPrintConfig {
  /**
   * Whether to force the watermark to be displayed when printing
   * @default false
   */
  enforceWatermark?: boolean
}
```

## Facade API

### Open Print Configuration Dialog

Using `FWorkbook.openPrintDialog` can open the print configuration dialog.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()

fWorkbook.openPrintDialog()
```

### Close Print Configuration Dialog

Using `FWorkbook.closePrintDialog` method can close the print configuration dialog.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.openPrintDialog()

// Close the print configuration dialog after 3 seconds
setTimeout(() => {
  fWorkbook.closePrintDialog()
}, 3000)
```

### Update Print Layout Configuration

Using [`FWorkbook.updatePrintConfig(config: ISheetPrintLayoutConfig)`](https://reference.univer.ai/en-US/classes/FWorkbook#updateprintconfig) method to update the print layout configuration.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const subUnitId = fWorksheet.getSheetId()

// Update print layout config
fWorkbook.updatePrintConfig({
  area: univerAPI.Enum.PrintArea.CurrentSheet, // print current sheet
  subUnitIds: [subUnitId],
  paperSize: univerAPI.Enum.PrintPaperSize.A4, // A4 paper size
  scale: univerAPI.Enum.PrintScale.FitPage, // fit content to page
  freeze: [univerAPI.Enum.PrintFreeze.Row], // freeze row headers
  margin: univerAPI.Enum.PrintPaperMargin.Normal, // normal margin
  // ... other settings
})

// Start printing with the updated configuration
fWorkbook.print()
```

<details>
  <summary>Here is the complete definition of `ISheetPrintLayoutConfig`:</summary>
  ```typescript
  /**
   * Configuration interface for sheet print layout settings
   */
  export interface ISheetPrintLayoutConfig {
    /**
     * Specifies which area of the sheet to print (e.g., current sheet, selection)
     */
    area: PrintArea
    /**
     * List of sub-unit IDs to print, can include specific ranges within units
     */
    subUnitIds: (string | { id: string, range: IRange })[]
    /**
     * Paper size setting (e.g., A4, Letter)
     */
    paperSize: PrintPaperSize
    /**
     * Page orientation (Portrait or Landscape)
     */
    direction: PrintDirection
    /**
     * Scale type for fitting content to page
     */
    scale: PrintScale
    /**
     * Custom scale percentage when scale type is custom
     */
    customScale: number
    /**
     * Array of freeze settings for rows and columns
     */
    freeze: PrintFreeze[]
    /**
     * Margin preset for the printed page
     */
    margin: PrintPaperMargin
    /**
     * Custom page dimensions when using custom paper size
     */
    pageSizeCustom?: { w: number, h: number }
    /**
     * Maximum number of rows to print per page
     */
    maxRowsEachPage: number
    /**
     * Maximum number of columns to print per page
     */
    maxColumnsEachPage: number
  }

  /**
   * Defines the area of the spreadsheet to be printed
   */
  export enum PrintArea {
    /** Print only the current active sheet */
    CurrentSheet = 'CurrentSheet',
    /** Print the entire workbook */
    workbook = 'Workbook',
    /** Print only the current selected range */
    CurrentSelection = 'CurrentSelection',
    /** Print all selected ranges across sheets */
    AllSelection = 'AllSelection',
  }

  /**
   * Defines the paper size for printing
   */
  export enum PrintPaperSize {
    /** Use the letter paper size */
    Letter = 'Letter',
    /** Use the tabloid paper size */
    Tabloid = 'Tabloid',
    /** Use the legal paper size */
    Legal = 'Legal',
    /** Use the statement paper size */
    Statement = 'Statement',
    /** Use the executive paper size */
    Executive = 'Executive',
    /** Use the folio paper size */
    Folio = 'Folio',
    /** Use the A3 paper size */
    A3 = 'A3',
    /** Use the A4 paper size */
    A4 = 'A4',
    /** Use the A5 paper size */
    A5 = 'A5',
    /** Use the B4 paper size */
    B4 = 'B4',
    /** Use the B5 paper size */
    B5 = 'B5',
  }

  /**
   * Defines the direction of the printed page
   */
  export enum PrintDirection {
    /** Portrait orientation */
    Portrait = 'Portrait',
    /** Landscape orientation */
    Landscape = 'Landscape',
  }

  /**
   * Defines the scale type for printing
   */
  export enum PrintScale {
    /** normal scale */
    Origin = 'Origin',
    /** Fit to width */
    FitWidth = 'FitWidth',
    /** Fit to height */
    FitHeight = 'FitHeight',
    /** Fit to page */
    FitPage = 'FitPage',
    /** Custom scale */
    Custom = 'Custom',
  }

  /**
   * Defines which elements should remain frozen when printing
   */
  export enum PrintFreeze {
    /** Keep row headers frozen when printing */
    Row = 'Row',
    /** Keep column headers frozen when printing */
    Column = 'Column',
  }

  /**
   * Defines the margin preset for the printed page
   */
  export enum PrintPaperMargin {
    /** Use the normal margin */
    Normal = 'Normal',
    /** Use the narrow margin */
    Narrow = 'Narrow',
    /** Use the wide margin */
    Wide = 'Wide',
    /** Not set any margin */
    None = 'None',
  }
  ```
</details>

### Update Print Render Configuration

Using [`FWorkbook.updatePrintRenderConfig(config: ISheetPrintRenderConfig)`](https://reference.univer.ai/en-US/classes/FWorkbook#updateprintrenderconfig) method to update the print render configuration.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()

// Update print layout config by default
fWorkbook.updatePrintConfig({})

// Update print render config
fWorkbook.updatePrintRenderConfig({
  gridlines: true, // show gridlines
  hAlign: univerAPI.Enum.PrintAlign.Middle, // horizontal align middle
  vAlign: univerAPI.Enum.PrintAlign.Middle, // vertical align middle
  headerFooter: [ // the array of header and footer elements to include, here is page numbers and worksheet name
    univerAPI.Enum.PrintHeaderFooter.PageSize,
    univerAPI.Enum.PrintHeaderFooter.WorksheetTitle,
  ],
  // ... other settings
})

// Start print
fWorkbook.print()
```

<details>
  <summary>Here is the complete definition of `ISheetPrintRenderConfig`:</summary>
  ```typescript
  /**
   * Configuration interface for sheet print rendering options
   */
  export interface ISheetPrintRenderConfig {
    /**
     * Whether to show gridlines in the printed output
     */
    gridlines: boolean
    /**
     * Horizontal alignment setting for content
     */
    hAlign: PrintAlign
    /**
     * Vertical alignment setting for content
     */
    vAlign: PrintAlign
    /**
     * Array of header and footer elements to include
     */
    headerFooter: PrintHeaderFooter[]
    /**
     * Detailed settings for header and footer content
     */
    headerFooterSetting: IPrintHeaderFooter
    /**
     * Whether using custom header/footer instead of presets
     */
    isCustomHeaderFooter?: boolean

    watermark?: Nullable<IWatermarkConfigWithType>
  }

  /**
   * Defines the available alignment options for printed content
   */
  export enum PrintAlign {
    /** horizontally align content to the left, vertically align content to the top */
    Start = 'Start',
    /** horizontally align content to the right, vertically align content to the bottom */
    End = 'End',
    /** horizontally align content to the center, vertically align content to the center */
    Middle = 'Middle',
  }

  /**
   * Defines the available placeholders for header and footer content
   */
  export enum PrintHeaderFooter {
    /** Insert current page numbers information */
    PageSize = 'PageSize',
    /** Insert workbook name */
    WorkbookTitle = 'WorkbookTitle',
    /** Insert worksheet name */
    WorksheetTitle = 'WorksheetTitle',
    /** Insert current date */
    Date = 'Date',
    /** Insert current time */
    Time = 'Time',
  }

  /**
   * Configuration interface for header and footer content positioning
   */
  export interface IPrintHeaderFooter {
    /** Content to display in the top-left section */
    topLeft: string
    /** Content to display in the top-center section */
    topCenter: string
    /** Content to display in the top-right section */
    topRight: string
    /** Content to display in the bottom-left section */
    bottomLeft: string
    /** Content to display in the bottom-center section */
    bottomCenter: string
    /** Content to display in the bottom-right section */
    bottomRight: string
  }
  ```
</details>

### Print

Using `FWorkbook.print` method can directly trigger the print dialog.

```typescript
// Using the default configuration you can pass in an empty object
workbook.updatePrintConfig({
  // ... Print layout configuration
})
workbook.updatePrintRenderConfig({
  // ... Print render configuration
})
workbook.print()
```

### Save Screenshot to Clipboard

Using the `FWorkbook.saveScreenshotToClipboard` method allows you to save the print data image to the clipboard.

Only available with a [license](en-US/guides/pro/license), users without a license will face usage restrictions, and the save operation will return `false`.

We use the Clipboard API to save the image to the clipboard, which may fail in non-secure network environments or unsupported browsers. A successful save will return `true`.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const result = await fWorkbook.saveScreenshotToClipboard()
```

### Get Screenshot of Selected Range

Using the `FRange.getScreenshot` method allows you to get a screenshot of the selected print data.

Only available with a [license](en-US/guides/pro/license), users without a license will face usage restrictions, and the save operation will return `false` on failure, or a base64 string of the image on success.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:D10')
fRange.getScreenshot()
```

### Event Listeners

The following events are available for the print functionality:

`univerAPI.Event.BeforeSheetPrintOpen` event is triggered before the print configuration dialog is opened.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintOpen, (params) => {
  const { workbook, worksheet } = params

  // Cancel open print configuration dialog operation
  params.cancel = true
})

// Remove the event listener, use `disposable.dispose()`.
```

`univerAPI.Event.SheetPrintOpen` event is triggered after the print configuration dialog is opened.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintOpen, (params) => {
  const { workbook, worksheet } = params
})

// Remove the event listener, use `disposable.dispose()`.
```

`univerAPI.Event.BeforeSheetPrintConfirm` event is triggered before the print confirmation dialog is opened.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintConfirm, (params) => {
  const { renderConfig, layoutConfig } = params

  // Cancel the print confirmation operation
  params.cancel = true
})

// Remove the event listener, use `disposable.dispose()`.
```

`univerAPI.Event.SheetPrintConfirmed` event is triggered after the print confirmation dialog is opened.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintConfirmed, (params) => {
  const { renderConfig, layoutConfig } = params
})

// Remove the event listener, use `disposable.dispose()`.
```

`univerAPI.Event.BeforeSheetPrintCanceled` event is triggered before the print cancellation operation.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintCanceled, (params) => {
  const { renderConfig, layoutConfig } = params

  // Cancel the print cancel operation
  params.cancel = true
})

// Remove the event listener, use `disposable.dispose()`.
```

`univerAPI.Event.SheetPrintCanceled` event is triggered after the print cancellation operation.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintCanceled, (params) => {
  const { renderConfig, layoutConfig } = params
})

// Remove the event listener, use `disposable.dispose()`.
```
